home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
System Booster
/
System Booster.iso
/
Textdisplayers
/
SuperMenu
/
SuperMenu.doc
< prev
next >
Wrap
Text File
|
1996-09-26
|
28KB
|
580 lines
SuperMenu 2.0
(c) 1990 by Paul T. Miller
All rights reserved.
INTRODUCTION
SUPERMENU is an information display system you can use to quickly and
easily display text files (and sections of text files) and pictures with the
press of a button. SuperMenu can be configured by you to perform in a variety
of ways - you have complete control over what buttons appear (and how they
look and are accessed), what section of the text is displayed (and it's
position, size and how it is referenced), how a picture is displayed on the
screen, how the program is run (and how it operates), and a variety of other
things.
SuperMenu can be run from the Workbench or CLI, and can be run once or
made resident for immediate activation by a user-defined hot-key. SuperMenu
uses two or more external files - one is the configuration file that makes
the magic (and open-endedness) of SuperMenu possible. With this file you have
complete control over all of SuperMenu's output and operation. The other file
(or files) contain the information you wish to display (usually an ASCII text
file or an IFF picture). Each text file can be typed in and edited with a
standard word processor, and must be in ASCII format.
SuperMenu has any number of uses, and it is constantly being updated and
laden with new features. See below for a few examples and the explanation of
SuperMenu's features.
USES
I) You have an application that you use often, but find yourself looking
to the manual for help a lot. With SuperMenu, you can type a text file
with any ASCII word processor. Within the file, you can separate the
various sections pertaining to a particular function, giving each one
a specific KEYWORD for which SuperMenu will search. Then you can create
a configuration file for SuperMenu, describing how you want it to look
and what functions to have help available for. When you're finished,
you can run SuperMenu, pick a function from the menu, and SuperMenu
will display that section of your file, allowing you to scroll through
it if it's more than a specified height. You can have all your favorite
help sections separated nicely and instantly available from within
SuperMenu. (this is the reason SuperMenu was written)
II) You've created a personal "disk-magazine" of all of your favorite
articles and pictures. SuperMenu will let you customize your disk so
any of these is instantly available at a gadget-click away.
III) Creating a picture sampler disk is as easy as putting the pictures and
SuperMenu on a disk and customizing the menus.
FUNCTIONS and PARAMETERS: SuperMenu's Custom Configuration File
With SuperMenu's configuration file, you can set up any of the following
customizable parameters:
1) SCREEN: This function is no longer supported (but is still in the
function list for future use). SuperMenu windows open up
automatically on the front-most screen.
2) FONT: The font you want to use in displaying the menu.
format = "FONT: Fontname Fontsize"
default = "Topaz 8"
3) COLUMNS: The maximum number of horizontal columns of menu choices
SuperMenu will display.
format = "COLUMNS: column_number"
default = 3
4) ROWS: The maximum number of vertical rows of menu choices
SuperMenu will display.
format = "ROWS: row_number"
default = 15
5) HSPACING: Horizontal Spacing, the number of pixels horizontally
between each of the menu choices.
format = "HSPACING: horizontal_spacing"
default = 10
6) VSPACING: Vertical Spacing, the number of pixels vertically
between each of the menu choices.
format = "VSPACING: vertical_spacing"
default = 5
7) TITLE: The title SuperMenu will display in the menu window. See
the NOTE below about string conventions (and the use of the
underscore instead of spaces).
format = "TITLE: Menu_window_title"
default = "SuperMenu v1.01"
8) KEYS: This option will automatically generate a keyboard-
equivalent for the first 26 menu options (A-Z).
format = "KEYS: ON <or> OFF"
default = OFF
9) BOXES: This option will draw a box around each of the menu
choices (making a button appearance).
format = "BOXES: ON <or> OFF"
default = OFF
10) STATUS: This option will display the amount displayed percentage
(and number of lines in the section) in the text window.
format = "STATUS: ON <or> OFF"
default = OFF
11) FILE: This defines a default "resident file" that is always in
memory (see below).
format = "FILE: resident_textfile_path"
default = NONE
12) PREFIX: This defines a 2-character prefix code used for finding
individual sections in the text files (see below).
format = "PREFIX: two-character_prefix_code"
default = "*:"
13) JUSTIFY: This sets the default justification used on your menu text.
format = "JUSTIFY: LEFT <or> RIGHT <or> CENTER"
default = LEFT
14) RESIDENT: This makes SuperMenu start up in the background, and wait
until the HELP Key is pressed before it displays its menu.
Closing the menu (with the CLOSE gadget) causes SuperMenu
to return to background mode until HELP is pressed again.
(Note: a feature has been added to customize the hot-key)
format = "RESIDENT: ON <or> OFF"
default = ON
15) MENUPOS: This allows you to set the position of the Menu Window
when the program is run (or when you press the hot-key
if the program is resident). X and Y are coordinates on
the screen. If either (or both) equal -1 then the menu
window will be centered in that axis.
format = "MENUPOS: left_edge top_edge"
default = -1 -1
16) QUIET: This turns off any printing of messages (either to the CLI
or the Workbench titlebar) by SuperMenu. Beware, you will
not know if an error occurs while it's loading, or whether
or not it was installed or removed correctly.
format = "QUIET: ON <or> OFF"
default = OFF
17) REOPEN: With this option turned on, SuperMenu will automatically
reopen any text files you left open when you made it
resident again (when you click on the CLOSEGADGET of the
menu window - only works when SuperMenu is made resident
with the resident option).
format = "REOPEN: ON <or> OFF"
default = ON
18) WINSIZE: This option allows you to set the size of the text window
when you click on an option. If there is not enough text
to fit vertically in the window, the window will open up
as to the set width, but only tall enough to display the
text. If the window is too small horizontally, you may not
be able to see all of your text. The window will open up
just large enough for the text in either direction if a
-1 is set for that size (and will be centered).
format = "WINSIZE: horizontal_size vertical_size"
default = -1 -1
19) COMKEY: User-defined command-key to invoke program. Must be a
RAWKEY code in hexadecimal (with "0x" prefix).
format = "COMKEY: 0xrawkey_code"
default = HELP KEY
20) QUALIFIER: User-defined qualifier key use to modify command key. Must
be a valid event Qualifier code in hexadecimal (with "0x"
prefix). See Qualifier Code Chart below for valid codes.
format = "QUALIFIER: 0xqualifier_code"
default = NO QUALIFIER
21) SCRSIZE: The user-defined size to constrain all SuperMenu output
to (width and height). A size of -1 will use the size of
that axis of the Workbench Screen.
format = "SCRSIZE: screen_width screen_height"
default = -1 -1
22) FADESPEED: This is the speed at which picture files set with the "F"
rendering style fade on and off the screen. The lower the
number, the faster the speed.
format = "FADESPEED: speed"
default = 2
If any of the above parameters are ommitted from the configuration file,
the defaults will be used.
NOTE: Any string (used in a screen, title, or file name) MUST have an
underscore character ("_") in place of ANY spaces in the string. If you
leave any spaces in the string (except at the end), SuperMenu will only
display the string up to that space. (So don't forget those underscores!)
Example: "Screen: Workbench_Screen" or "Title: My_Help_File"
NOTE: When you make SuperMenu resident (with the RESIDENT: command - this
should NOT be confused with the "resident file" - see below), the only
way to clear SuperMenu from memory is to press CONTROL-C while the menu
window is being displayed. Running SuperMenu again will also remove
itself.
Common Qualifier Codes
Key Code
---------------- ------
Left SHIFT 0x0001
Right SHIFT 0x0002
Either SHIFT Key 0x0003
CONTROL 0x0008
Left ALT 0x0010
Right ALT 0x0020
Either ALT Key 0x0030
Left AMIGA 0x0040
Right AMIGA 0x0080
Either AMIGA Key 0x00C0
RESIDENT FILE
Any text file may be made "resident" at the start of the program by
specifying it in the parameter list in the Configuration File.
SuperMenu will load this text file and keep it resident while SuperMenu
is running. If one of your buttons makes a reference to this file, it will
not have to be loaded again, because it's already in memory. This greatly
improves the speed at which the text is display for often-used text files.
The resident file MUST NOT be a picture file, but a standard text file only.
KEYWORDS
Any text file may be broken down into sections, with each section having
its own "keyword" to help SuperMenu find it. This allows you to have many
different functions explained in one text file, rather than having a bunch
of separate files. Placing all of your function information in one file, and
then making that file resident, completely removes any disk access once the
program is running, and provides almost instant feedback to the text
requested.
To place keywords in your text file, locate the line just before the
section you want to start at, and type in some identifying word that you want
to be used as a keyword. This word must be on a line of its own, MUST BE IN
ALL UPPERCASE, and must have a two-character keyword prefix in front of it
(which you set in the configuration file with the PREFIX: parameter, if you
don't want to use the default of "*:"). This keyword prefix is provided so
your keyword won't get mixed up with other text in the file, and SuperMenu
will know it's a keyword ("*:" was chosen because it is unlikely it would
occur randomly at the beginning of a line - use your own 2-character prefix
if you prefer).
When you click on a gadget that uses a keyword, SuperMenu will search
through the file for that prefix code and keyword, and will display the text
until it encounters THE NEXT keyword or the end of the file.
CONFIGURATION FILE
SuperMenu requires this configuration file to run. Even if you want all
of the default parameters and don't require a resident file or optional
window title, you've still got to define your menu options, and this is
where that is done, too!
The format of the SuperMenu conguration file is somewhat strict, and is
defined below:
If SuperMenu is run from the CLI, and no command-line parameters are used,
it will look for a configuration file named "sm.config" which resides in the
"s:" device (usually the "s" directory on the disk where your startup-
sequence is). If you have a configuration file named something else, you can
direct SuperMenu to load it instead of the default one by specifying your
config file name after the name of the program (ie. "SuperMenu config.file").
If you're running SuperMenu from the Workbench, you may set an alternate
configuration file by setting one of the ToolTypes with the Workbench Info
option. Use the ADD command and type "CONFIG=filename" into the tooltype bar,
where "filename" is the name of your configuration file. Don't forget to SAVE
the modified Info file.
The file must be standard ASCII format, and the FIRST LINE of the file
MUST BE the string "SMCF1", which stands for "SuperMenu Configuration File
version 1". This is provided for upward compatibility, and SuperMenu WILL NOT
RUN if this header string is missing.
Next come your parameter definitions, in any order you choose, with the
parameter command first (in upper or lower case) followed by a colon
(ie. "Screen:" or "SCREEN:" or "screen:"), and a space. Then comes the
actual parameter value, be it a string (see the above NOTE:) or number (some
commands may require more than one parameter, such as the font name and
size - ie. "Font: Topaz 8"). After that, you can place a semi-colon (";")
followed by a comment of your choice (no longer than 40 characters).
NOTE: There must be a space between the Parameter Command and each of the
successive parameter values. There should be no quotes surrounding
any text strings (and no spaces in them either, see above NOTE).
Everything is ignored after the correct number of parameter values,
so you may place a short comment if you wish (place it after a
semi-colon, so you'll know it's a comment). See the sample config
file to examine a typical configuration file structure.
After all of your parameter options, place the word "DATA" in upper-case
on a line of its own. This tells SuperMenu that the menu definitions will
follow. Don't forget this! SuperMenu won't work properly without it.
Next come your menu definitions, each of which follow a strict line format
of their own. Each successive line may begin with one of the following:
TITLE (a non-selectable choice used for delimiting sections of
choices - ie. "User Functions" or "Digitized Pictures")
MENU (an actual choice definition - used for TEXT files)
PICT (a choice definitions - used to load PICTURE files)
BLANK (a blank line in the menu between two choices)
The format of a "TITLE" option would be the following:
"TITLE title_name color rendering_flags"
"title_name" is the text to place in the title
"color" is the rendering color of the title (0-3 on Workbench Screen)
"rendering_flags" are the rendering style of the title (see below)
Example: "TITLE User_Functions: 3 BU"
This title ("User Functions:") will be drawn in color 3 and will be
BOLDFACE and UNDERLINED.
The format of a "MENU" option would be the following:
"MENU menu_name color rendering_flags file_name keyword"
"menu_name" is the text to place in the menu
"color" is the rendering color of the menu (0-3 on Workbench Screen)
"rendering_flags" are the rendering style of the menu (see below)
"file_name" is the name of the text file to access for this option
"keyword" is the UPPERCASE word used to search for the specific section
Example: "MENU Load 3 N DOC:program.HELP LOAD"
This menu ("Load") will be drawn in color 3 and will be a normal style.
When it is selected, the text file "DOC:program.HELP" will be loaded
and the section under the keyword "LOAD" will be displayed.
NOTE: If the file this option is supposed to load is the resident file,
use an asterisk ("*") in place of the filename. Also, do not place
the keyword prefix code in front of the keyword. If this option has
no keyword, and you just want the whole file displayed (or to start
at the beginning) specify a keyword of "*".
The format of a "PICT" option would be the following:
"PICT menu_name color rendering_flags file_name showstyle"
"menu_name" is the text to place in the menu
"color" is the rendering color of the menu (0-3 on Workbench Screen)
"rendering_flags" are the rendering style of the menu (see below)
"file_name" is the name of the IFF file to access for this option
"showstyle" is the rendering style of the image (see below)
Example: "PICT HappyFace 2 U PICS:HappyFace.pic F"
This menu will be drawn in color 2 and will be underlined.
When it is selected, the picture file "PICS:HappyFace.pic" will be
loaded and faded in ("F" style)
NOTE: In order to use picture files from SuperMenu, it is necessary to have
Christian Weber's iff.library in your libs: directory. If this is not
present when SuperMenu is run, it will disable displaying of menu items
concerned with pictures. HAM pictures will always be rendered with a CUT.
The "BLANK" option has no parameters. Just place it on a line by itself.
RENDERING FLAGS
You may select specific rendering styles for your title or menu text
within the menu window by using one-character codes in the "rendering style"
field of the option. You may use any of the following:
N - normal text (no special rendering style)
B - BOLDFACE
I - ITALICS
U - UNDERLINED
L - LEFT-justify text within gadget field
R - RIGHT-justify text within gadget field
C - CENTER text within gadget field
(Boldface, Italics, and Underlined may all be combined in any way you
like, ie. BIU or BI or UB, etc. The last justification flag encountered
will be the one used. If no justification flag is supplied, the default
one will be used, as set in the configuration file.)
IMAGE RENDERING STYLES
You may select one of the following to tell SuperMenu how to display your
picture file. ONE of them MUST be used. If any character other than one below
if used, "C" is the default.
C (or c) - CUT; cut the picture on the screen instantly
F (or f) - FADE; fade the picture on and off the screen
* Press the left mouse button when finished viewing the picture.
NOTE: If any of your option text or filenames have spaces in them, replace
the spaces with underscores ("_"). Do NOT forget this, or SuperMenu is
likely to run unpredictably. For example, a title of "User Functions:" should
really be defined as "User_Functions:".
TITLE, MENU, PICT, or BLANK options may have comments after the last
parameter, just like the configuration parameters.
The last line in the configuration file must be the string "ENDDATA" in
all UPPERCASE and on a line of its own. SuperMenu will display the titles,
menus, and blank lines in the menu window in the same order you placed them
into the configuration file, so make sure they are layed out the way you
want them first. Also, when SuperMenu draws a title, menu, or blank on the
last line of the menu window (as set by the ROWS: configuration parameter),
the next one will be drawn at the top of the window in the next column over.
Keep in mind that your menu window will reflect the way you set up your
maximum sizes and choices in the config file. If you have fewer options
than the maximum sizes allow, SuperMenu will display a menu window just
large enough for your options, automatically.
NOTE: You can use a different configuration file when SuperMenu is run from
the CLI by typing the path name of the config file you want to use after
the program's name (ie. "Run SuperMenu t:my_config").
You may include the QUIET option after the program name and config file
name to turn off program messages (ie. "Run SuperMenu t:my_config QUIET"),
or you may include this in the configuration file parameter list instead.
NOTE: You can close open text windows with the window's CLOSEGADGET, or by
pressing the ENTER key while the window is active.
Hints for using SuperMenu effectively:
1) If you've developed a config file and some text to be used in a LORES
display, you will have to set the margins in your text processor so that
the text lines are under 40 characters in length (make sure the edited
file is saved in a Text or ASCII format). Now you will have to inform
SuperMenu that its output should be constrained to a width of 320 (it will
automatically be set to the width of the Workbench Screen, 640, when it's
run) by using the SCRSIZE: option in the configuration file with a width
set to 320 (the height can stay at -1, the default height, but still must
be set: "SCRSIZE: 320 -1").
2) Whenever you need to add something new to the menu and your text files,
you can easily accomplish this by typing in the new text where it needs to
go (and giving it a keyword) and inserting a new MENU item for it in the
configuration file. SuperMenu was designed to be easy to expand and simple
to customize.
3) If you're running SuperMenu from the Workbench, all you need is to copy
the default icon to the name you want, and fill in the path name of the
SuperMenu program into the Default Tool section in the Info file, and the
configuration file to use in the ToolTypes section with "CONFIG=filename"
(this allows several icons to access the same program, each using
different configuration files).
4) To quit SuperMenu (and remove it from memory), type a CONTROL-C while the
menu window is active, or run the program again.
5) To make SuperMenu re-resident, click on the CLOSEGADGET on the menu window
or press the ESCAPE key while a textwindow is active.
** MODIFICATION HISTORY **
V2.00 RELEASE NOTES 03/03/90
- Add picture support
- FADESPEED config option
- Fix handler
V1.62 RELEASE NOTES 12/14/89
- Remove SCREEN: config option. SuperMenu's windows now open on the
currently-active (front-most) screen.
- Add SCRSIZE: config option to force SuperMenu to constrain all of its
output (menu and text windows) to a certain size.
- Sorry. Still no ANSI...
V1.61 RELEASE NOTES 12/03/89
- Moved some pointers around having to do with the textwindow titlebar
Now keeps track of title and percentage in window info section so we
don't go around hacking up memory blocks when we make un/resident
(also brings code size down about 1K - neato)
V1.60 RELEASE NOTES 11/28/89
- Yeah!! Workbench bug was NOT a bug - this thing wouldn't work at ALL
except under my development environment (don't know why) - I changed
the handler code to an older format (with an assembler stub) and it
now works FINE! Hurrah! (I though Lattice 5.02 worked OK with reg.
parameters - guess not...)
- Text windows now display choice name in title bar with status info
V1.51 PRERELEASE NOTES 11/28/89
- Program now sets up its own port (for future AREXX compatibility)
so it knows where it is. If you run it twice, it will remove itself
(as if you did it manually with CTRL-C)
- Multiply-opened windows now open just below (if possible) the bottom-
most window on the screen (open one, move it to the top, and then
open some more for a screen full of little windows)
- Workbench bug still there (crashes horribly when run from WB, I don't
know why!! <sob> - works great from CLI, though, so put it in your
startup-sequence (later found to be WRONG - see v1.60 notes)
- Boxes bug still there, but it's no big deal anyway - don't use them
V1.50 PRERELEASE NOTES 11/26/89
- User-defined command and qualifier keys for invoking program
V1.40 PRERELEASE NOTES 11/25/89
- Size of the text window may be set with WINSIZE option
- Windows left open when made resident will re-open automatically
next time program is invoked (only in Resident mode)
V1.30 PRERELEASE NOTES 11/23/89
- Multiple or sections of the same text files may be open at once
- Multiple open text files may be manipulated independently
- QUIET config/command-line option for no messages printed
- Bug in BOXES mode makes strange lines all over (hmmmm...)
- Crazy bug in Workbench implementation, freezes for no apparent reason
after installing
V1.20 PRERELEASE NOTES 11/20/89
- Workbench support added: CONFIG ToolType sets config file
- MenuPos parameter added in config file to set menu window position
- If menu window is moved and closed, it opens in place it was closed
V1.10 PRERELEASE NOTES 11/16/89
- Resident option, can be called up at any time with HELP key
- CONTROL-C on menu window removes SuperMenu from memory
- Minor menu window heuristics bugs fixed
- Still need workbench icon selecting config file
V1.01 BETA NOTES 11/15/89
- User-supplied config filename from command-line
- Justification parameters for menu text
- Resident parameter for upward compatibility to next revision
V1.00 BETA NOTES 11/14/89
- Doesn't support ANSI control codes in text files
- No command-line options
- No workbench icon support
AUTHOR NOTE
SuperMenu is SHAREWARE. You may use and/or redistribute this program
as you like, but if you find it exceptionally useful (or are just feeling
generous, or you like my work, or my writing style, or anything else possibly
worthwhile), please feel free to send me a small donation of $10 or so. This
could make a struggling college student's day (and believe me, IT DOES!), and
may go into helping me write more interesting and helpful programs (as well
as some possible enhancements to SuperMenu - which I may already be planning!
How about picture support? Hmmmm.... At the rate I'm adding stuff to this
program it should be able to scramble eggs within six months!)
Here's a deal for you! Send me $20.00 and I'll send you the latest and
greatest, new and improved, debugged and enhanced (smells nice too), version
of SuperMenu on disk and register you for notification of future updates and
other cool stuff (I'll also throw in some of my other ShareWare and PD stuff
too). This includes the lastest manual revision and any SuperMenu scripts I
happen to create or come across (also the upcoming blender attachment and
turnip twaddler, absolutely FREE). What a baagin!
Send any comments, criticisms, suggestions, donations, etc. to:
Paul T. Miller
129 Orchard Avenue
Rocky Mount, VA 24151
or call me at (703) 483-8219 for a chat or something.
------------ What are these "CUT HERE" lines REALLY for, anyway? -----------
_________
| _______ |
|| || AMIGA HAS THE "ELEMENTS" OF CREATIVITY
|| //||
|| // ||
||\\ // || "What could be better than my Lattice `C'
|| \\/ || and some Dr. Pepper?"
||_______|| "I love my Amiga 1000!"
|_________| ___
______________ |---|
| | |. '|
| --- | ____ \./ <- supposed to be a brandy snifter
|______________|| __ | |
|============| |____| _|_ (This probably looks weird in non-interlace..)
----------------------------------------------------------------------------